# GNU Guix System Explorer

“What’s this?”, you ask.  It’s a hack, initially written for [a FOSDEM
2021 talk](https://fosdem.org/2021/schedule/event/gnuguix/), that allows
you to navigate the
[services](https://guix.gnu.org/manual/en/html_node/Services.html) of
your [Guix System](https://guix.gnu.org)
[configuration](https://guix.gnu.org/manual/en/html_node/Using-the-Configuration-System.html)
and the connections among them.

## Exploring your system

It’s very bare-bones, my friend!  Assuming the Guix modules are in your
`GUILE_LOAD_PATH`—it’s the case on Guix System—you can run, say:

```sh
./explore.scm /run/current-system/configuration.scm
```

That spawns a web server on port 8080, which you can talk to from your
browser at `http://localhost:8080`.  And what do you see there?

![Animation of showing interaction with the Guix System Explorer.](demo.gif)

Voilà!

## What is this showing?

If you’ve tried [`guix system
extension-graph`](https://guix.gnu.org/manual/en/html_node/Invoking-guix-system.html)
before, it is showing something similar.  On the graph displayed, each
node represents a _service_ of your system configuration, and each edge
represents a _service extension_.  Essential services are shown as red
circles, [“base”
services](https://guix.gnu.org/manual/en/html_node/Base-Services.html#index-_0025base_002dservices-1)
are represented as smaller red circles, and user services are smaller
gray circles.  When **hovering over a service**, its documentation is
displayed at the top left.

When **clicking on a service**, its _value_ gets displayed.  For example,
the value of the `udev` service is a record containing (1) the (e)udev
package it uses, and (2) the set of udev rules.  For the `openssh`
service, the value is [a record listing the various `sshd`
options](https://guix.gnu.org/manual/en/html_node/Networking-Services.html#index-openssh_002dconfiguration).

The graph shows, for example, an arrow from the `openssh` to the
`accounts` service, which is responsible for setting up user accounts.
When **clicking on this arrow**, we see the “value” that `openssh`
_contributes_ to `accounts`: it’s a list consisting of the `sshd` group
and the `sshd` user account—the “privilege separation” account used by
`sshd`.

Last, when **double-clicking on a service**, you can see the effect of
[_folding_ all the services that contribute to
it](https://guix.gnu.org/manual/en/html_node/Service-Reference.html#index-fold_002dservices).
For example, when double-clicking on `shepherd-root`, all the services
with an incoming edge contribute a value to this service—a Shepherd
service—and are no longer displayed.  At this point, clicking on
`shepherd-root` shows its new value: a list of [`shepherd-service`
records](https://guix.gnu.org/manual/en/html_node/Shepherd-Services.html#index-shepherd_002dservice).

Ultimately, all services can be folded into
[`system`](https://guix.gnu.org/manual/en/html_node/Service-Reference.html#index-system_002dservice_002dtype),
which the the “root” of all services, representing the final, assembled
operating system.

## Why?

Modern GNU/Linux distributions are complex beasts and it’s hard to get
the big picture.  This tool aims to help users answer questions such as:
What components make up my system?  How are they composed together?  How
does the high-level configuration of a service translate into the
configuration of lower-level services?

Ultimately, I would like to think of this tool not just as a helper for
Guix System users, but also as an educational tool—a tool to help users
and enthusiasts learn how things are glued together.  It’s about
_empowering users_, reducing the gap between “those who know” and “those
who use”.

## What’s next?

Who knows what’s next!  There are certainly glitches here and there in
the user interface that could be fixed, and convenience features that
could be added.  Perhaps this tool could be made part of Guix proper, as
a new `guix system explore` sub-command?

So far the tool is only about exploring the system.  What if we allowed
users to _edit_ their system configuration right from the user
interface?  Food for thought!

## Join us!

Things you can do:

  - Watch the accompanying FOSDEM 2021 talk, [_Declaratively
    Yours—Composing system abstractions with
    GNU Guix_](https://fosdem.org/2021/schedule/event/gnuguix/).
  - Try it yourself, and [hack
    it](https://notabug.org/civodul/guix-explorer)!
  - [Get in touch with Guix!](https://guix.gnu.org/en/contact/)
  
Ludovic Courtès, February 2021.
